From 0ef8f5256765526075f2a25eac056c6e753b1849 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Javier=20Jard=C3=B3n?= Date: Sat, 28 Nov 2009 02:59:06 +0100 Subject: [PATCH] Move documentation from templates to inline comments: GtkWidget https://bugzilla.gnome.org/show_bug.cgi?id=597865 --- docs/reference/gtk/tmpl/gtkwidget.sgml | 2867 ------------------------ gtk/gtkwidget.c | 184 +- gtk/gtkwidget.h | 359 ++- 3 files changed, 520 insertions(+), 2890 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkwidget.sgml diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml deleted file mode 100644 index c127bfc225..0000000000 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ /dev/null @@ -1,2867 +0,0 @@ - -GtkWidget - - -Base class for all widgets - - - -GtkWidget introduces style -properties - these are basically object properties that are stored -not on the object, but in the style object associated to the widget. Style -properties are set in resource files. -This mechanism is used for configuring such things as the location of the -scrollbar arrows through the theme, giving theme authors more control over the -look of applications without the need to write a theme engine in C. - - -Use gtk_widget_class_install_style_property() to install style properties for -a widget class, gtk_widget_class_find_style_property() or -gtk_widget_class_list_style_properties() to get information about existing -style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or -gtk_widget_style_get_valist() to obtain the value of a style property. - - - -GtkWidget as GtkBuildable - -The GtkWidget implementation of the GtkBuildable interface supports a -custom <accelerator> element, which has attributes named key, -modifiers and signal and allows to specify accelerators. - - -A UI definition fragment specifying an accelerator - - - -]]> - -In addition to accelerators, GtkWidget also support a -custom <accessible> element, which supports actions and relations. -Properties on the accessible implementation of an object can be set by accessing the -internal child "accessible" of a GtkWidget. - -A UI definition fragment specifying an accessible - - I am a Label for a Button - - - - Click the button. - - - - - Clickable Button - - - -]]> - - - - - - - - - - - - - - - - - - - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@arg1: -@Returns: - - - - - - -@widget: the object which received the signal. -@arg1: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@arg1: - - - - - - -@widget: the object which received the signal. -@drag_context: - - - - - - -@widget: the object which received the signal. -@drag_context: - - - - - - -@widget: the object which received the signal. -@drag_context: -@data: -@info: -@time: - - - - - - -@widget: the object which received the signal. -@drag_context: -@x: -@y: -@data: -@info: -@time: - - - - - - -@widget: the object which received the signal. -@drag_context: -@x: -@y: -@time: -@Returns: - - - - - - -@widget: the object which received the signal. -@drag_context: - - - - - - -@widget: the object which received the signal. -@arg1: -@arg2: -@Returns: - - - - - - -@widget: the object which received the signal. -@drag_context: -@time: - - - - - - -@widget: the object which received the signal. -@drag_context: -@x: -@y: -@time: -@Returns: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@arg1: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@arg1: - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: -@widget2: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@arg1: -@Returns: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@arg1: -@Returns: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@arg1: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@old_parent: - - - - - - -@widget: the object which received the signal. -@Returns: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@arg1: -@arg2: -@arg3: -@arg4: -@Returns: - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@arg1: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@data: -@info: -@time: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@data: -@time: - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@arg1: -@Returns: - - - - - - -@widget: the object which received the signal. -@allocation: - - - - - - -@widget: the object which received the signal. -@requisition: - - - - - - -@widget: the object which received the signal. -@state: - - - - - - -@widget: the object which received the signal. -@previous_style: - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - -@widget: the object which received the signal. -@event: -@Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -activate_signal -The signal to emit when a widget of this class is activated, -gtk_widget_activate() handles the emission. Implementation of this -signal is optional. - - - -set_scroll_adjustment_signal -This signal is emitted when a widget of this class is added -to a scrolling aware parent, gtk_widget_set_scroll_adjustments() -handles the emission. -Implementation of this signal is optional. - - -@parent_class: -@activate_signal: -@set_scroll_adjustments_signal: - - - -Tells about certain properties of the widget. - - -@GTK_TOPLEVEL: - widgets without a real parent, as there are #GtkWindows and - #GtkMenus have this flag set throughout their lifetime. - Toplevel widgets always contain their own #GdkWindow. -@GTK_NO_WINDOW: - Indicative for a widget that does not provide its own #GdkWindow. - Visible action (e.g. drawing) is performed on the parent's #GdkWindow. -@GTK_REALIZED: - Set by gtk_widget_realize(), unset by gtk_widget_unrealize(). - A realized widget has an associated #GdkWindow. -@GTK_MAPPED: - Set by gtk_widget_map(), unset by gtk_widget_unmap(). - Only realized widgets can be mapped. It means that gdk_window_show() - has been called on the widgets window(s). -@GTK_VISIBLE: - Set by gtk_widget_show(), unset by gtk_widget_hide(). Implies that a - widget will be mapped as soon as its parent is mapped. -@GTK_SENSITIVE: - Set and unset by gtk_widget_set_sensitive(). - The sensitivity of a widget determines whether it will receive - certain events (e.g. button or key presses). One premise for - the widget's sensitivity is to have this flag set. -@GTK_PARENT_SENSITIVE: - Set and unset by gtk_widget_set_sensitive() operations on the - parents of the widget. - This is the second premise for the widget's sensitivity. Once - it has %GTK_SENSITIVE and %GTK_PARENT_SENSITIVE set, its state is - effectively sensitive. This is expressed (and can be examined) by - the #GTK_WIDGET_IS_SENSITIVE macro. -@GTK_CAN_FOCUS: - Determines whether a widget is able to handle focus grabs. -@GTK_HAS_FOCUS: - Set by gtk_widget_grab_focus() for widgets that also - have %GTK_CAN_FOCUS set. The flag will be unset once another widget - grabs the focus. -@GTK_CAN_DEFAULT: - The widget is allowed to receive the default action via - gtk_widget_grab_default(). -@GTK_HAS_DEFAULT: - The widget currently is receiving the default action. -@GTK_HAS_GRAB: - Set by gtk_grab_add(), unset by gtk_grab_remove(). It means that the - widget is in the grab_widgets stack, and will be the preferred one for - receiving events other than ones of cosmetic value. -@GTK_RC_STYLE: - Indicates that the widget's style has been looked up through the rc - mechanism. It does not imply that the widget actually had a style - defined through the rc mechanism. -@GTK_COMPOSITE_CHILD: - Indicates that the widget is a composite child of its parent; see - gtk_widget_push_composite_child(), gtk_widget_pop_composite_child(). -@GTK_NO_REPARENT: - Unused since before GTK+ 1.2, will be removed in a future version. -@GTK_APP_PAINTABLE: - Set and unset by gtk_widget_set_app_paintable(). - Must be set on widgets whose window the application directly draws on, - in order to keep GTK+ from overwriting the drawn stuff. See - for a detailed - description of this flag. -@GTK_RECEIVES_DEFAULT: - The widget when focused will receive the default action and have - %GTK_HAS_DEFAULT set even if there is a different widget set as default. -@GTK_DOUBLE_BUFFERED: - Set and unset by gtk_widget_set_double_buffered(). - Indicates that exposes done on the widget should be - double-buffered. See for a - detailed discussion of how double-buffering works in GTK+ and - why you may want to disable it for special cases. -@GTK_NO_SHOW_ALL: - - - -Gets the type of a widget. - - -@wid: a #GtkWidget. - - - - -Returns the current state of the widget, as a #GtkStateType. - - -@wid: a #GtkWidget. - - - - -Returns the saved state of the widget, as a #GtkStateType. - - -The saved state will be restored when a widget gets sensitive -again, after it has been made insensitive with gtk_widget_set_state() -or gtk_widget_set_sensitive(). - - -@wid: a #GtkWidget. - - - - -Returns the widget flags from @wid. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is a toplevel widget. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget doesn't have an own #GdkWindow. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is realized. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is mapped. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is visible. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is mapped and visible. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the #GTK_SENSITIVE flag has be set on the widget. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the #GTK_PARENT_SENSITIVE flag has be set on the widget. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is effectively sensitive. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is able to handle focus grabs. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget has grabbed the focus and no other -widget has done so more recently. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is allowed to receive the default action -via gtk_widget_grab_default(). - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget when focused will receive the default action -even if there is a different widget set as default. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget currently is receiving the default action. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is in the grab_widgets stack, and will be -the preferred one for receiving events other than ones of cosmetic value. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget's style has been looked up through the rc -mechanism. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the widget is a composite child of its parent. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the #GTK_APP_PAINTABLE flag has been set on the widget. - - -@wid: a #GtkWidget. - - - - -Evaluates to %TRUE if the #GTK_DOUBLE_BUFFERED flag has been set on the widget. - - -@wid: a #GtkWidget. - - - - -Turns on certain widget flags. - - -@wid: a #GtkWidget. -@flag: the flags to set. - - - - -Turns off certain widget flags. - - -@wid: a #GtkWidget. -@flag: the flags to unset. - - - - -The type of the callback functions used for e.g. iterating over -the children of a container, see gtk_container_foreach(). - - -@widget: the widget to operate on -@data: user-supplied data - - - - -A GtkRequisition represents the desired size of a widget. See - for more information. - - -@width: the widget's desired width -@height: the widget's desired height - - - -A GtkAllocation of a widget represents region which has been allocated to the -widget by its parent. It is a subregion of its parents allocation. See - for more information. - - -@x: the X position of the widget's area relative to its parents allocation. -@y: the Y position of the widget's area relative to its parents allocation. -@width: the width of the widget's allocated area. -@height: the height of the widget's allocated area. - - - - - - - - - - - - -@x: -@y: -@width: -@height: -@x_set: -@y_set: - - - - - - -@offset_x: -@offset_y: -@shape_mask: - - - - - - -@GTK_WIDGET_HELP_TOOLTIP: -@GTK_WIDGET_HELP_WHATS_THIS: - - - - - - -@type: -@first_property_name: -@Varargs: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: -@widget_pointer: - - - - - - - -@widget: -@first_property_name: -@Varargs: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: -@area: - - - - - - - -@widget: -@requisition: - - - - - - - -@widget: -@requisition: - - - - - - - -@widget: -@allocation: - - - - - - - -@widget: -@accel_signal: -@accel_group: -@accel_key: -@accel_mods: -@accel_flags: - - - - - - - -@widget: -@accel_group: -@accel_key: -@accel_mods: -@Returns: - - - - - - - -@widget: -@accel_path: -@accel_group: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@signal_id: -@Returns: - - - - - - - -@widget: -@event: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@new_parent: - - - - - - - -@widget: -@area: -@intersection: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: - - - - - - - -@widget: - - - - - - - -@widget: -@name: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@state: - - - - - - - -@widget: -@sensitive: - - - - - - - -@widget: -@parent: - - - - - - - -@widget: -@parent_window: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@x: -@y: - - - - - - - -@widget: -@width: -@height: - - - - - - - -@widget: -@events: - - - - - - - -@widget: -@events: - - - - - - - -@widget: -@mode: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@widget_type: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@colormap: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@x: -@y: - - - - - - - -@widget: -@ancestor: -@Returns: - - - - - - - -@src_widget: -@dest_widget: -@src_x: -@src_y: -@dest_x: -@dest_y: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@style: - - - - -Equivalent to gtk_widget_set_style (widget, NULL). - - -@widget: a #GtkWidget. -@Deprecated: Use gtk_widget_set_style() with a %NULL @style argument instead. - - - - - - - -@widget: - - - - - - - -@widget: -@Returns: - - - - -Equivalent to gtk_widget_set_style (widget, NULL). - - -@widget: a #GtkWidget. -@Deprecated: Use gtk_widget_set_style() with a %NULL @style argument instead. - - - - -Reset the styles of @widget and all descendents, so when -they are looked up again, they get the correct values -for the currently loaded RC file settings. - - -This function is not useful for applications. - - -@widget: a #GtkWidget. - - - - - - - -@cmap: - - - - - - - - - - - - - - -@colormap: - - - - - - - -@Returns: - - - - - - - -@Returns: - - - - - - - -@Returns: - - - - - - - -@widget: -@dir: - - - - - - - -@GTK_TEXT_DIR_NONE: -@GTK_TEXT_DIR_LTR: -@GTK_TEXT_DIR_RTL: - - - - - - -@widget: -@Returns: - - - - - - - -@dir: - - - - - - - -@Returns: - - - - - - - -@widget: -@shape_mask: -@offset_x: -@offset_y: - - - - - - - -@widget: -@shape_mask: -@offset_x: -@offset_y: - - - - - - - -@widget: -@path_length: -@path: -@path_reversed: - - - - - - - -@widget: -@path_length: -@path: -@path_reversed: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@style: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@state: -@color: - - - - - - - -@widget: -@state: -@color: - - - - - - - -@widget: -@state: -@color: - - - - - - - -@widget: -@state: -@color: - - - - - - - -@widget: -@font_desc: - - - - - - - -@widget: -@primary: -@secondary: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@text: -@Returns: - - - - - - - -@widget: -@stock_id: -@size: -@detail: -@Returns: - - - - - - - - - - - - - - - - - - - - - -@widget: - - - - - - - -@widget: -@x: -@y: -@width: -@height: - - - - - - - -@widget: -@x: -@y: -@width: -@height: - - - - - - - -@widget: - - - - - - - -@widget: -@app_paintable: - - - - - - - -@widget: -@double_buffered: - - - - - - - -@widget: -@redraw_on_allocate: - - - - - - - -@widget: -@name: - - - - - - - -@widget: -@hadjustment: -@vadjustment: -@Returns: - - - - - - - -@widget: -@group_cycling: -@Returns: - - - - - - - -@klass: -@pspec: - - - - - - - -@klass: -@pspec: -@parser: - - - - - - - -@klass: -@property_name: -@Returns: - - - - - - - -@klass: -@n_properties: -@Returns: - - - - - - - -@widget: -@region: -@Returns: - - - - - - - -@widget: -@event: -@Returns: - - - - - - - -@widget: -@first_property_name: -@Varargs: - - - - - - - -@widget: -@property_name: -@value: - - - - - - - -@widget: -@first_property_name: -@var_args: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@direction: -@Returns: - - - - - - - -@widget: -@child_property: - - - - - - - -@widget: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@selection: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@width: -@height: - - - - -This function is deprecated; it does nothing. - - - - - - -This function is deprecated; it does nothing. - - -@visual: a visual - - - - - - - -@widget: -@is_visible: - - - - -This function is deprecated; it does nothing. - - -@visual: a visual - - - - - - - -@widget: -@width: -@height: - - - - -This function is deprecated; it does nothing. - - -@widget: a #GtkWidget -@visual: a visual - - - - - - - -@widget: - - - - - - - -@widget: -@no_show_all: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@label: - - - - - - - -@widget: -@label: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: - - - - - - - -@widget: -@direction: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@markup: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@text: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@custom_window: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@has_tooltip: - - - - - - - -@widget: - - - - - - - -@widget: -@clip_rect: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@allocation: - - - - - - - -@widget: -@allocation: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@can_default: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@can_focus: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@has_window: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@visible: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@Returns: - - - - - - - -@widget: -@window: - - - - - - - -@widget: -@receives_default: - - - - - - - -@widget: -@Returns: - - - - - - - -@requisition: -@Returns: - - - - - - - -@requisition: - - diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 5677fd73f4..36bbcb4ee5 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -55,6 +55,74 @@ #include "gtkbuilderprivate.h" #include "gtkalias.h" +/** + * SECTION:gtkwidget + * @Short_description: Base class for all widgets + * @Title: GtkWidget + * + * GtkWidget is the base class all widgets in GTK+ derive from. It manages the + * widget lifecycle, states and style. + * + * + * GtkWidget introduces style + * properties - these are basically object properties that are stored + * not on the object, but in the style object associated to the widget. Style + * properties are set in resource files. + * This mechanism is used for configuring such things as the location of the + * scrollbar arrows through the theme, giving theme authors more control over the + * look of applications without the need to write a theme engine in C. + * + * + * Use gtk_widget_class_install_style_property() to install style properties for + * a widget class, gtk_widget_class_find_style_property() or + * gtk_widget_class_list_style_properties() to get information about existing + * style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or + * gtk_widget_style_get_valist() to obtain the value of a style property. + * + * + * + * GtkWidget as GtkBuildable + * + * The GtkWidget implementation of the GtkBuildable interface supports a + * custom <accelerator> element, which has attributes named key, + * modifiers and signal and allows to specify accelerators. + * + * + * A UI definition fragment specifying an accelerator + * + * + * + * ]]> + * + * + * In addition to accelerators, GtkWidget also support a + * custom <accessible> element, which supports actions and relations. + * Properties on the accessible implementation of an object can be set by accessing the + * internal child "accessible" of a GtkWidget. + * + * + * A UI definition fragment specifying an accessible + * + * I am a Label for a Button + * + * + * + * Click the button. + * + * + * + * + * Clickable Button + * + * + * + * ]]> + * + * + */ + #define WIDGET_CLASS(w) GTK_WIDGET_GET_CLASS (w) #define INIT_PATH_SIZE (512) @@ -708,6 +776,10 @@ gtk_widget_class_init (GtkWidgetClass *klass) TRUE, GTK_PARAM_READWRITE)); + /** + * GtkWidget::show: + * @widget: the object which received the signal. + */ widget_signals[SHOW] = g_signal_new (I_("show"), G_TYPE_FROM_CLASS (gobject_class), @@ -716,6 +788,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkWidget::hide: + * @widget: the object which received the signal. + */ widget_signals[HIDE] = g_signal_new (I_("hide"), G_TYPE_FROM_CLASS (gobject_class), @@ -724,6 +801,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkWidget::map: + * @widget: the object which received the signal. + */ widget_signals[MAP] = g_signal_new (I_("map"), G_TYPE_FROM_CLASS (gobject_class), @@ -732,6 +814,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkWidget::unmap: + * @widget: the object which received the signal. + */ widget_signals[UNMAP] = g_signal_new (I_("unmap"), G_TYPE_FROM_CLASS (gobject_class), @@ -740,6 +827,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkWidget::realize: + * @widget: the object which received the signal. + */ widget_signals[REALIZE] = g_signal_new (I_("realize"), G_TYPE_FROM_CLASS (gobject_class), @@ -748,6 +840,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkWidget::unrealize: + * @widget: the object which received the signal. + */ widget_signals[UNREALIZE] = g_signal_new (I_("unrealize"), G_TYPE_FROM_CLASS (gobject_class), @@ -756,6 +853,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkWidget::size-request: + * @widget: the object which received the signal. + * @requisition: + */ widget_signals[SIZE_REQUEST] = g_signal_new (I_("size-request"), G_TYPE_FROM_CLASS (gobject_class), @@ -765,6 +868,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) _gtk_marshal_VOID__BOXED, G_TYPE_NONE, 1, GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); + + /** + * GtkWidget::size-allocate: + * @widget: the object which received the signal. + * @allocation: + */ widget_signals[SIZE_ALLOCATE] = g_signal_new (I_("size-allocate"), G_TYPE_FROM_CLASS (gobject_class), @@ -775,6 +884,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) G_TYPE_NONE, 1, GDK_TYPE_RECTANGLE | G_SIGNAL_TYPE_STATIC_SCOPE); + /** + * GtkWidget::state-changed: + * @widget: the object which received the signal. + * @state: + */ widget_signals[STATE_CHANGED] = g_signal_new (I_("state-changed"), G_TYPE_FROM_CLASS (gobject_class), @@ -906,6 +1020,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) g_cclosure_marshal_VOID__PARAM, G_TYPE_NONE, 1, G_TYPE_PARAM); + + /** + * GtkWidget::mnemonic-activate: + * @widget: the object which received the signal. + * @arg1: + */ widget_signals[MNEMONIC_ACTIVATE] = g_signal_new (I_("mnemonic-activate"), G_TYPE_FROM_CLASS (gobject_class), @@ -915,6 +1035,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) _gtk_marshal_BOOLEAN__BOOLEAN, G_TYPE_BOOLEAN, 1, G_TYPE_BOOLEAN); + + /** + * GtkWidget::grab-focus: + * @widget: the object which received the signal. + */ widget_signals[GRAB_FOCUS] = g_signal_new (I_("grab-focus"), G_TYPE_FROM_CLASS (gobject_class), @@ -923,6 +1048,14 @@ gtk_widget_class_init (GtkWidgetClass *klass) NULL, NULL, _gtk_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkWidget::focus: + * @widget: the object which received the signal. + * @direction: + * + * Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. + */ widget_signals[FOCUS] = g_signal_new (I_("focus"), G_TYPE_FROM_CLASS (object_class), @@ -932,6 +1065,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) _gtk_marshal_BOOLEAN__ENUM, G_TYPE_BOOLEAN, 1, GTK_TYPE_DIRECTION_TYPE); + + /** + * GtkWidget::move-focus: + * @widget: the object which received the signal. + * @direction: + */ widget_signals[MOVE_FOCUS] = g_signal_new_class_handler (I_("move-focus"), G_TYPE_FROM_CLASS (object_class), @@ -1503,6 +1642,13 @@ gtk_widget_class_init (GtkWidgetClass *klass) G_TYPE_BOOLEAN, 1, GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE); + /** + * GtkWidget::selection-notify-event: + * @widget: the object which received the signal. + * @event: + * + * Returns: %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. + */ widget_signals[SELECTION_NOTIFY_EVENT] = g_signal_new (I_("selection-notify-event"), G_TYPE_FROM_CLASS (gobject_class), @@ -1513,6 +1659,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) G_TYPE_BOOLEAN, 1, GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE); + /** + * GtkWidget::selection-received: + * @widget: the object which received the signal. + * @data: + * @time: + */ widget_signals[SELECTION_RECEIVED] = g_signal_new (I_("selection-received"), G_TYPE_FROM_CLASS (gobject_class), @@ -1524,6 +1676,13 @@ gtk_widget_class_init (GtkWidgetClass *klass) GTK_TYPE_SELECTION_DATA | G_SIGNAL_TYPE_STATIC_SCOPE, G_TYPE_UINT); + /** + * GtkWidget::selection-get: + * @widget: the object which received the signal. + * @data: + * @info: + * @time: + */ widget_signals[SELECTION_GET] = g_signal_new (I_("selection-get"), G_TYPE_FROM_CLASS (gobject_class), @@ -1831,7 +1990,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) G_TYPE_INT, G_TYPE_UINT); - /** + /** * GtkWidget::drag-data-get: * @widget: the object which received the signal * @drag_context: the drag context @@ -2143,6 +2302,12 @@ gtk_widget_class_init (GtkWidgetClass *klass) _gtk_boolean_handled_accumulator, NULL, _gtk_marshal_BOOLEAN__VOID, G_TYPE_BOOLEAN, 0); + + /** + * GtkWidget::show-help: + * @widget: the object which received the signal. + * @help_type: + */ widget_signals[SHOW_HELP] = g_signal_new (I_("show-help"), G_TYPE_FROM_CLASS (gobject_class), @@ -2152,6 +2317,11 @@ gtk_widget_class_init (GtkWidgetClass *klass) _gtk_marshal_BOOLEAN__ENUM, G_TYPE_BOOLEAN, 1, GTK_TYPE_WIDGET_HELP_TYPE); + + /** + * GtkWidget::accel-closures-changed: + * @widget: the object which received the signal. + */ widget_signals[ACCEL_CLOSURES_CHANGED] = g_signal_new (I_("accel-closures-changed"), G_TYPE_FROM_CLASS (gobject_class), @@ -2179,6 +2349,7 @@ gtk_widget_class_init (GtkWidgetClass *klass) _gtk_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GDK_TYPE_SCREEN); + /** * GtkWidget::can-activate-accel: * @widget: the object which received the signal @@ -6799,6 +6970,17 @@ reset_rc_styles_recurse (GtkWidget *widget, gpointer data) NULL); } + +/** + * gtk_widget_reset_rc_styles: + * @widget: a #GtkWidget. + * + * Reset the styles of @widget and all descendents, so when + * they are looked up again, they get the correct values + * for the currently loaded RC file settings. + * + * This function is not useful for applications. + */ void gtk_widget_reset_rc_styles (GtkWidget *widget) { diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h index ed286636d5..21c58d10c9 100644 --- a/gtk/gtkwidget.h +++ b/gtk/gtkwidget.h @@ -41,8 +41,62 @@ G_BEGIN_DECLS -/* The flags that are used by GtkWidget on top of the - * flags field of GtkObject. +/** + * GtkWidgetFlags: + * @GTK_TOPLEVEL: widgets without a real parent, as there are #GtkWindows and + * #GtkMenus have this flag set throughout their lifetime. + * Toplevel widgets always contain their own #GdkWindow. + * @GTK_NO_WINDOW: Indicative for a widget that does not provide its own #GdkWindow. + * Visible action (e.g. drawing) is performed on the parent's #GdkWindow. + * @GTK_REALIZED: Set by gtk_widget_realize(), unset by gtk_widget_unrealize(). + * A realized widget has an associated #GdkWindow. + * @GTK_MAPPED: Set by gtk_widget_map(), unset by gtk_widget_unmap(). + * Only realized widgets can be mapped. It means that gdk_window_show() + * has been called on the widgets window(s). + * @GTK_VISIBLE: Set by gtk_widget_show(), unset by gtk_widget_hide(). Implies that a + * widget will be mapped as soon as its parent is mapped. + * @GTK_SENSITIVE: Set and unset by gtk_widget_set_sensitive(). + * The sensitivity of a widget determines whether it will receive + * certain events (e.g. button or key presses). One premise for + * the widget's sensitivity is to have this flag set. + * @GTK_PARENT_SENSITIVE: Set and unset by gtk_widget_set_sensitive() operations on the + * parents of the widget. + * This is the second premise for the widget's sensitivity. Once + * it has %GTK_SENSITIVE and %GTK_PARENT_SENSITIVE set, its state is + * effectively sensitive. This is expressed (and can be examined) by + * the #GTK_WIDGET_IS_SENSITIVE macro. + * @GTK_CAN_FOCUS: Determines whether a widget is able to handle focus grabs. + * @GTK_HAS_FOCUS: Set by gtk_widget_grab_focus() for widgets that also + * have %GTK_CAN_FOCUS set. The flag will be unset once another widget + * grabs the focus. + * @GTK_CAN_DEFAULT: The widget is allowed to receive the default action via + * gtk_widget_grab_default() and will reserve space to draw the default if possible + * @GTK_HAS_DEFAULT: The widget currently is receiving the default action and + * should be drawn appropriately if possible + * @GTK_HAS_GRAB: Set by gtk_grab_add(), unset by gtk_grab_remove(). It means that the + * widget is in the grab_widgets stack, and will be the preferred one for + * receiving events other than ones of cosmetic value. + * @GTK_RC_STYLE: Indicates that the widget's style has been looked up through the rc + * mechanism. It does not imply that the widget actually had a style + * defined through the rc mechanism. + * @GTK_COMPOSITE_CHILD: Indicates that the widget is a composite child of its parent; see + * gtk_widget_push_composite_child(), gtk_widget_pop_composite_child(). + * @GTK_NO_REPARENT: Unused since before GTK+ 1.2, will be removed in a future version. + * @GTK_APP_PAINTABLE: Set and unset by gtk_widget_set_app_paintable(). + * Must be set on widgets whose window the application directly draws on, + * in order to keep GTK+ from overwriting the drawn stuff. See + * for a detailed + * description of this flag. + * @GTK_RECEIVES_DEFAULT: The widget when focused will receive the default action and have + * %GTK_HAS_DEFAULT set even if there is a different widget set as default. + * @GTK_DOUBLE_BUFFERED: Set and unset by gtk_widget_set_double_buffered(). + * Indicates that exposes done on the widget should be + * double-buffered. See for a + * detailed discussion of how double-buffering works in GTK+ and + * why you may want to disable it for special cases. + * @GTK_NO_SHOW_ALL: + * + * Tells about certain properties of the widget. */ typedef enum { @@ -55,28 +109,14 @@ typedef enum GTK_PARENT_SENSITIVE = 1 << 10, GTK_CAN_FOCUS = 1 << 11, GTK_HAS_FOCUS = 1 << 12, - - /* widget is allowed to receive the default via gtk_widget_grab_default - * and will reserve space to draw the default if possible - */ GTK_CAN_DEFAULT = 1 << 13, - - /* the widget currently is receiving the default action and should be drawn - * appropriately if possible - */ GTK_HAS_DEFAULT = 1 << 14, - GTK_HAS_GRAB = 1 << 15, GTK_RC_STYLE = 1 << 16, GTK_COMPOSITE_CHILD = 1 << 17, GTK_NO_REPARENT = 1 << 18, GTK_APP_PAINTABLE = 1 << 19, - - /* the widget when focused will receive the default action and have - * HAS_DEFAULT set even if there is a different widget set as default - */ GTK_RECEIVES_DEFAULT = 1 << 20, - GTK_DOUBLE_BUFFERED = 1 << 21, GTK_NO_SHOW_ALL = 1 << 22 } GtkWidgetFlags; @@ -100,37 +140,221 @@ typedef enum /* Macros for extracting various fields from GtkWidget and GtkWidgetClass. */ +/** + * GTK_WIDGET_TYPE: + * @wid: a #GtkWidget. + * + * Gets the type of a widget. + */ #define GTK_WIDGET_TYPE(wid) (GTK_OBJECT_TYPE (wid)) + +/** + * GTK_WIDGET_STATE: + * @wid: a #GtkWidget. + * + * Returns the current state of the widget, as a #GtkStateType. + */ #define GTK_WIDGET_STATE(wid) (GTK_WIDGET (wid)->state) + +/** + * GTK_WIDGET_SAVED_STATE: + * @wid: a #GtkWidget. + * + * Returns the saved state of the widget, as a #GtkStateType. + * + * The saved state will be restored when a widget gets sensitive + * again, after it has been made insensitive with gtk_widget_set_state() + * or gtk_widget_set_sensitive(). + */ #define GTK_WIDGET_SAVED_STATE(wid) (GTK_WIDGET (wid)->saved_state) + /* Macros for extracting the widget flags from GtkWidget. */ +/** + * GTK_WIDGET_FLAGS: + * @wid: a #GtkWidget. + * + * Returns the widget flags from @wid. + */ #define GTK_WIDGET_FLAGS(wid) (GTK_OBJECT_FLAGS (wid)) + +/** + * GTK_WIDGET_TOPLEVEL: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is a toplevel widget. + */ #define GTK_WIDGET_TOPLEVEL(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_TOPLEVEL) != 0) + +/** + * GTK_WIDGET_NO_WINDOW: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget doesn't have an own #GdkWindow. + */ #define GTK_WIDGET_NO_WINDOW(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_NO_WINDOW) != 0) + +/** + * GTK_WIDGET_REALIZED: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is realized. + */ #define GTK_WIDGET_REALIZED(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_REALIZED) != 0) + +/** + * GTK_WIDGET_MAPPED: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is mapped. + */ #define GTK_WIDGET_MAPPED(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_MAPPED) != 0) + +/** + * GTK_WIDGET_VISIBLE: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is visible. + */ #define GTK_WIDGET_VISIBLE(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_VISIBLE) != 0) + +/** + * GTK_WIDGET_DRAWABLE: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is mapped and visible. + */ #define GTK_WIDGET_DRAWABLE(wid) (GTK_WIDGET_VISIBLE (wid) && GTK_WIDGET_MAPPED (wid)) + +/** + * GTK_WIDGET_SENSITIVE: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the #GTK_SENSITIVE flag has be set on the widget. + */ #define GTK_WIDGET_SENSITIVE(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_SENSITIVE) != 0) + +/** + * GTK_WIDGET_PARENT_SENSITIVE: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the #GTK_PARENT_SENSITIVE flag has be set on the widget. + */ #define GTK_WIDGET_PARENT_SENSITIVE(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_PARENT_SENSITIVE) != 0) + +/** + * GTK_WIDGET_IS_SENSITIVE: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is effectively sensitive. + */ #define GTK_WIDGET_IS_SENSITIVE(wid) (GTK_WIDGET_SENSITIVE (wid) && \ GTK_WIDGET_PARENT_SENSITIVE (wid)) +/** + * GTK_WIDGET_CAN_FOCUS: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is able to handle focus grabs. + */ #define GTK_WIDGET_CAN_FOCUS(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_CAN_FOCUS) != 0) + +/** + * GTK_WIDGET_HAS_FOCUS: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget has grabbed the focus and no other + * widget has done so more recently. + */ #define GTK_WIDGET_HAS_FOCUS(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_HAS_FOCUS) != 0) + +/** + * GTK_WIDGET_CAN_DEFAULT: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is allowed to receive the default action + * via gtk_widget_grab_default(). + */ #define GTK_WIDGET_CAN_DEFAULT(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_CAN_DEFAULT) != 0) + +/** + * GTK_WIDGET_HAS_DEFAULT: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget currently is receiving the default action. + */ #define GTK_WIDGET_HAS_DEFAULT(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_HAS_DEFAULT) != 0) + +/** + * GTK_WIDGET_HAS_GRAB: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is in the grab_widgets stack, and will be + * the preferred one for receiving events other than ones of cosmetic value. + */ #define GTK_WIDGET_HAS_GRAB(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_HAS_GRAB) != 0) + +/** + * GTK_WIDGET_RC_STYLE: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget's style has been looked up through the rc + * mechanism. + */ #define GTK_WIDGET_RC_STYLE(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_RC_STYLE) != 0) + +/** + * GTK_WIDGET_COMPOSITE_CHILD: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget is a composite child of its parent. + */ #define GTK_WIDGET_COMPOSITE_CHILD(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_COMPOSITE_CHILD) != 0) + +/** + * GTK_WIDGET_APP_PAINTABLE: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the #GTK_APP_PAINTABLE flag has been set on the widget. + */ #define GTK_WIDGET_APP_PAINTABLE(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_APP_PAINTABLE) != 0) + +/** + * GTK_WIDGET_RECEIVES_DEFAULT: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the widget when focused will receive the default action + * even if there is a different widget set as default. + */ #define GTK_WIDGET_RECEIVES_DEFAULT(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_RECEIVES_DEFAULT) != 0) + +/** + * GTK_WIDGET_DOUBLE_BUFFERED: + * @wid: a #GtkWidget. + * + * Evaluates to %TRUE if the #GTK_DOUBLE_BUFFERED flag has been set on the widget. + */ #define GTK_WIDGET_DOUBLE_BUFFERED(wid) ((GTK_WIDGET_FLAGS (wid) & GTK_DOUBLE_BUFFERED) != 0) - + + /* Macros for setting and clearing widget flags. */ +/** + * GTK_WIDGET_SET_FLAGS: + * @wid: a #GtkWidget. + * @flag: the flags to set. + * + * Turns on certain widget flags. + */ #define GTK_WIDGET_SET_FLAGS(wid,flag) G_STMT_START{ (GTK_WIDGET_FLAGS (wid) |= (flag)); }G_STMT_END + +/** + * GTK_WIDGET_UNSET_FLAGS: + * @wid: a #GtkWidget. + * @flag: the flags to unset. + * + * Turns off certain widget flags. + */ #define GTK_WIDGET_UNSET_FLAGS(wid,flag) G_STMT_START{ (GTK_WIDGET_FLAGS (wid) &= ~(flag)); }G_STMT_END #define GTK_TYPE_REQUISITION (gtk_requisition_get_type ()) @@ -138,7 +362,6 @@ typedef enum /* forward declaration to avoid excessive includes (and concurrent includes) */ typedef struct _GtkRequisition GtkRequisition; -typedef GdkRectangle GtkAllocation; typedef struct _GtkSelectionData GtkSelectionData; typedef struct _GtkWidgetClass GtkWidgetClass; typedef struct _GtkWidgetAuxInfo GtkWidgetAuxInfo; @@ -146,11 +369,38 @@ typedef struct _GtkWidgetShapeInfo GtkWidgetShapeInfo; typedef struct _GtkClipboard GtkClipboard; typedef struct _GtkTooltip GtkTooltip; typedef struct _GtkWindow GtkWindow; -typedef void (*GtkCallback) (GtkWidget *widget, - gpointer data); -/* A requisition is a desired amount of space which a - * widget may request. +/** + * GtkAllocation: + * @x: the X position of the widget's area relative to its parents allocation. + * @y: the Y position of the widget's area relative to its parents allocation. + * @width: the width of the widget's allocated area. + * @height: the height of the widget's allocated area. + * + * A GtkAllocation of a widget represents region which has been allocated to the + * widget by its parent. It is a subregion of its parents allocation. See + * for more information. + */ +typedef GdkRectangle GtkAllocation; + +/** + * GtkCallback: + * @widget: the widget to operate on + * @data: user-supplied data + * + * The type of the callback functions used for e.g. iterating over + * the children of a container, see gtk_container_foreach(). + */ +typedef void (*GtkCallback) (GtkWidget *widget, + gpointer data); + +/** + * GtkRequisition: + * @width: the widget's desired width + * @height: the widget's desired height + * + * A GtkRequisition represents the desired size of a widget. See + * for more information. */ struct _GtkRequisition { @@ -229,6 +479,24 @@ struct _GtkWidget GtkWidget *GSEAL (parent); }; +/** + * GtkWidgetClass: + * @parent_class: + * @activate_signal: + * @set_scroll_adjustments_signal: + * + * activate_signal + * The signal to emit when a widget of this class is activated, + * gtk_widget_activate() handles the emission. Implementation of this + * signal is optional. + * + * + * set_scroll_adjustment_signal + * This signal is emitted when a widget of this class is added + * to a scrolling aware parent, gtk_widget_set_scroll_adjustments() + * handles the emission. + * Implementation of this signal is optional. + */ struct _GtkWidgetClass { /* The object class structure needs to be the first @@ -669,10 +937,39 @@ GdkPixmap * gtk_widget_get_snapshot (GtkWidget *widget, GdkRectangle *clip_rect); #ifndef GTK_DISABLE_DEPRECATED + +/** + * gtk_widget_set_visual: + * @widget: a #GtkWidget + * @visual: a visual + * + * This function is deprecated; it does nothing. + */ #define gtk_widget_set_visual(widget,visual) ((void) 0) + +/** + * gtk_widget_push_visual: + * @visual: a visual + * + * This function is deprecated; it does nothing. + */ #define gtk_widget_push_visual(visual) ((void) 0) + +/** + * gtk_widget_pop_visual: + * + * This function is deprecated; it does nothing. + */ #define gtk_widget_pop_visual() ((void) 0) + +/** + * gtk_widget_set_default_visual: + * @visual: a visual + * + * This function is deprecated; it does nothing. + */ #define gtk_widget_set_default_visual(visual) ((void) 0) + #endif /* GTK_DISABLE_DEPRECATED */ /* Accessibility support */ @@ -735,7 +1032,25 @@ void gtk_widget_modify_font (GtkWidget *widget, PangoFontDescription *font_desc); #ifndef GTK_DISABLE_DEPRECATED + +/** + * gtk_widget_set_rc_style: + * @widget: a #GtkWidget. + * + * Equivalent to gtk_widget_set_style (widget, NULL). + * + * Deprecated: Use gtk_widget_set_style() with a %NULL @style argument instead. + */ #define gtk_widget_set_rc_style(widget) (gtk_widget_set_style (widget, NULL)) + +/** + * gtk_widget_restore_default_style: + * @widget: a #GtkWidget. + * + * Equivalent to gtk_widget_set_style (widget, NULL). + * + * Deprecated: Use gtk_widget_set_style() with a %NULL @style argument instead. + */ #define gtk_widget_restore_default_style(widget) (gtk_widget_set_style (widget, NULL)) #endif -- 2.30.2